<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Non-Durable Transactions</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Getting Started with Berkeley DB, Java Edition Transaction Processing" />
    <link rel="up" href="usingtxns.html" title="Chapter 3. Transaction Basics" />
    <link rel="prev" href="usingtxns.html" title="Chapter 3. Transaction Basics" />
    <link rel="next" href="abortresults.html" title="Aborting a Transaction" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Non-Durable Transactions</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="usingtxns.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 3. Transaction Basics</th>
          <td width="20%" align="right"> <a accesskey="n" href="abortresults.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="nodurabletxn"></a>Non-Durable Transactions</h2>
          </div>
        </div>
      </div>
      <p>
            As previously noted, by default transaction commits are
            durable because they cause the modifications performed
            under the transaction to be synchronously recorded in 
            your on-disk log files.  However, it is possible to use 
            non-durable transactions.
        </p>
      <p>
            You may want non-durable transactions for performance
            reasons. For example, you might be using transactions
            simply for the isolation guarantee. 
            
            
            <span>
                In this case, you might want to relax the synchronized write to disk that JE normally performs
                as part of a transaction commit. Doing so means that your data will still make it to disk; however,
                your application will not necessarily have to wait for the disk I/O to complete before it can
                perform another database operation. This can greatly improve throughput for some workloads.
            </span>
        </p>
      <p>
            To relax the durability guarantee for your transactions,
            you use the <code class="classname">Durability</code> class to
            define the durability policy that you want to use. The 
            <code class="classname">Durability</code> class constructor takes
            three arguments, only one of which is interesting for a
            standalone transactional application:
        </p>
      <div class="itemizedlist">
        <ul type="disc">
          <li>
            <p>
                    The synchronization policy for the local machine. 
                </p>
          </li>
          <li>
            <p>
                    The synchronization policy for Replicas. Used only for
                    JE HA applications.
                </p>
          </li>
          <li>
            <p>
                    The acknowledgement policy. Again, this is required
                    only for JE HA applications.
                </p>
          </li>
        </ul>
      </div>
      <p>
            We describe JE High Availability Applications in the
            <em class="citetitle">Berkeley DB, Java Edition Getting Started with High Availability Applications</em> guide.
        </p>
      <p>
            The synchronization policy that you give the
            <code class="classname">Durability</code> class constructor can be
            one of the following:
        </p>
      <div class="itemizedlist">
        <ul type="disc">
          <li>
            <p>
                        <code class="literal">Durability.SyncPolicy.SYNC</code>
                    </p>
            <p>
                        Write and synchronously flush the log to disk upon
                        transaction commit. This offers the most durable
                        transaction configuration because the commit
                        operation will not return until all of the disk I/O
                        is complete. But, conversely, this offers the worse
                        possible write performance because disk I/O is an
                        expensive and time-consuming operation.
                    </p>
            <p>
                        This is the default synchronization policy. A
                        transaction that uses this policy is considered to
                        be <span class="emphasis"><em>durable</em></span>.
                    </p>
          </li>
          <li>
            <p>
                        <code class="literal">Durability.SyncPolicy.NO_SYNC</code>
                    </p>
            <p>
                        This causes JE to not synchronously force any data
                        to disk upon transaction commit.  That is, the
                        modifications are held entirely inside the JVM and
                        the modifications are not forced to the file system
                        for long-term storage.  Note, however, that the
                        data will eventually make it to the filesystem
                        (assuming no application or OS crashes) as a part
                        of JE's management of its logging buffers and/or
                        cache. 
                    </p>
            <p>
                        This form of a commit provides a weak durability
                        guarantee because data loss can occur due to an
                        application, JVM, or OS crash. In fact, this
                        represents the least durable configuration that you
                        can provide for your transactions. But it also
                        offers much better write performance than the other
                        options.
                    </p>
          </li>
          <li>
            <p>
                        <code class="literal">Durability.SyncPolicy.WRITE_NO_SYNC</code>
                    </p>
            <p>
                        This causes data to be synchronously written to the
                        OS's file system buffers upon transaction commit.
                        The data will eventually be written to disk, but
                        this occurs when the operating system chooses to
                        schedule the activity; the transaction commit can
                        complete successfully before this disk I/O is
                        performed by the OS. 
                    </p>
          </li>
          <li>
            <p>
                        This form of commit protects you against
                        application and JVM crashes, but not against OS
                        crashes. This method offers less room for the
                        possibility of data loss than does NO_SYNC.
                    </p>
          </li>
        </ul>
      </div>
      <p>
                You can specify your durability policy on an
                environment-wide basis by creating a
                <code class="classname">Durability</code> class and then giving it
                to <code class="methodname">EnvironmentConfig.setDurability()</code>. 
                You can also override the environment default durability
                policy on a transaction-by-transaction basis by providing a 
                <code class="classname">Durability</code> class to the 
                <code class="classname">TransactionConfig</code> object you use to
                configure your transaction using the 
                <code class="methodname">TransactionConfig.setDurability()</code>
                method.
            </p>
      <p>
                For example:
            </p>
      <pre class="programlisting">package je.txn;

import com.sleepycat.je.Database;
import com.sleepycat.je.DatabaseConfig;
import com.sleepycat.je.DatabaseEntry;
import com.sleepycat.je.DatabaseException;
<strong class="userinput"><code>import com.sleepycat.je.Durability;</code></strong>
import com.sleepycat.je.Environment;
import com.sleepycat.je.EnvironmentConfig;
import com.sleepycat.je.Transaction;
<strong class="userinput"><code>import com.sleepycat.je.TransactionConfig;</code></strong>

import java.io.File;

...

Database myDatabase = null;
Environment myEnv = null;
try {
    <strong class="userinput"><code>Durability defaultDurability = 
        new Durability(Durability.SyncPolicy.NO_SYNC, 
                       null,    // unused by non-HA applications. 
                       null);   // unused by non-HA applications.  </code></strong>

    EnvironmentConfig myEnvConfig = new EnvironmentConfig();
    myEnvConfig.setTransactional(true);
    <strong class="userinput"><code>myEnvConfig.setDurability(defaultDurability);</code></strong>
    myEnv = new Environment(new File("/my/env/home"),
                              myEnvConfig);

    // Open the database. Create it if it does not already exist.
    DatabaseConfig dbConfig = new DatabaseConfig();
    dbConfig.setTransactional(true);
    myDatabase = myEnv.openDatabase(null,
                                    "sampleDatabase",
                                    dbConfig);

    String keyString = "thekey";
    String dataString = "thedata";
    DatabaseEntry key = 
        new DatabaseEntry(keyString.getBytes("UTF-8"));
    DatabaseEntry data = 
        new DatabaseEntry(dataString.getBytes("UTF-8"));

    <strong class="userinput"><code>Durability newDurability = 
        new Durability(Durability.SyncPolicy.WRITE_NO_SYNC, 
                       null,    // unused by non-HA applications. 
                       null);   // unused by non-HA applications.

    TransactionConfig tc = new TransactionConfig();
    tc.setDurability(newDurability);
    Transaction txn = myEnv.beginTransaction(null, tc);</code></strong>
        
    try {
        myDatabase.put(txn, key, data);
        txn.commit();
    } catch (Exception e) {
        if (txn != null) {
            txn.abort();
            txn = null;
        }
    }

} catch (DatabaseException de) {
    // Exception handling goes here
} </pre>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="usingtxns.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="usingtxns.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="abortresults.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Chapter 3. Transaction Basics </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Aborting a Transaction</td>
        </tr>
      </table>
    </div>
  </body>
</html>
